COMMENT ⊗   VALID 00003 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Description of WAITS User Datagram Protocol service:
C00004 00003	MTAPEs for WAITS User Datagram Protocol service:
C00011 ENDMK
C⊗;
Description of WAITS User Datagram Protocol service:

The User Datagram Protocol (UDP) is provided by using the device IMP with
special MTAPE UUOs.  It is not possible (or meaningful) to intermix UDP and
TCP operations on the same IMP channel.  However, a closed IMP channel may
be reused for either TCP or UDP without releasing it.

UDP is a packet-based protocol, unlike TCP, which provides a stream of
data; nevertheless we have the concept of a "connection" associated with a
UDP IMP channel.  The three parameters which define a connection are the
foreign host, foreign port, and local port.  Once these are set for a
channel, any incoming packets matching them may be read.  Doing packet
output sets the connection parameters to the values used for that packet.

MTAPEs for WAITS User Datagram Protocol service:

	MTAPE <chan>,ADR
ADR:	30			;Write a UDP packet
	<status bits returned>
	<local port>
	<user addr of packet data>
	<packet length>
	<foreign port>
	<foreign host>

A UDP packet is sent to the foreign host, with the given local and foreign ports
(the right 16 bits of each).  You must supply the packet length, in bytes, in
word 4, and the address of the first word in word 3.  The bytes should be stored
4 per word, left aligned.  You must give the foreign port and host, but may ask
the system to generate a local port number by making word 2 negative.

No indication of the success or failure of the sending operation is returned.
UDP is not a reliable protocol, so you must handle acknowledgement and
retransmission yourself if necessary.  The returned status bits will be non-zero
if you are in an illegal state to perform this operation.


	MTAPE <chan>,ADR
ADR:	31			;Read or request a UDP packet
	<status bits returned>
	<local port>
	<user addr of packet data>
	<packet length returned>
	<foreign port>
	<foreign host>

This MTAPE waits for a packet, unless word 3 is zero, in which case it returns
immediately, but will cause the system to direct an incoming packet to you.  You
may place 0 in word 5 or 6 if you want to read a packet from any foreign host or
port.  The system will return the received values when it returns a packet.  If
you make word 2 negative, the system will generate a new local port number,
place this port number in word 2, and then prepare to give you a packet
addressed to that port.

If word 3 is non-zero, the system will wait for a packet, and place it into the
buffer pointed to by word 3.  (You must make sure that this buffer is large
enough for the maximum packet size you expect.)  The length of the packet, in
bytes, is returned in word 4.

If the input timeout (set by MTAPE 17) expires, this UUO will return 0 in word 4
and set the TMO bit in the I/O status word.


	MTAPE <chan>,ADR
ADR:	32			;Wait for requested UDP packet
	<status bits returned>
	<local port>
	<user addr of packet data>
	<packet length returned>
	<foreign port returned>
	<foreign host returned>

If a packet was requested by giving MTAPE 31 with word 3 zero, then this MTAPE
can be used to read an arriving packet.  (For instance, after a user interrupt
indicating the packet's arrival.)  If no packet has yet arrived when you give
this MTAPE, your job will start waiting for one.  It is an error to execute
MTAPE 32 if not preceded by MTAPE 31.  If an application requires reading
several packets on the same local port, a new MTAPE 31 must be given for each.


	MTAPE <chan>,ADR
ADR:	33			;Get a free UDP port
	<local port returned>

This MTAPE asks the system to generate a new local port number, and return it
in word 1 of the MTAPE block, without sending or receiving any packets.

----------

Typical uses of these MTAPEs:

To exchange packets with a process on a specific port at a foreign host:

  1. Give an MTAPE 31 with -1 as the local port, 0 as the buffer address, and
     your chosen foreign host and port.  This will return without waiting.

  2. Take the local port returned in word 2 of the MTAPE 31 block, and place it
     in word 2 of an MTAPE 30 block.  Then send out a packet.

  3. Execute MTAPE 32 to wait for the response.  Since you did MTAPE 31 before
     MTAPE 30, any response, no matter how soon it arrives, will be directed by
     the system to you.

To act as a server on a particular local port:

  1. Do MTAPE 31, waiting for a packet on your chosen port from any foreign
     host and port.

  2. When a packet arrives, use the returned foreign host and port values in
     an MTAPE 30 block to send a reply.

  3. Go to step 1 to repeat the process for the next service request.